/**
 * InventoryNavGraph.kt
 * 包声明和导入
 * 包名：com.example.inventoryapp.ui.navigation表明这是导航相关的代码
 * 导入：
 * Compose 相关组件
 * Navigation 库的核心类和函数
 * 应用特定的屏幕组件和路由定义
 */
package com.example.inventoryapp.ui.navigation

import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.navigation.NavHostController
import androidx.navigation.NavType
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.navArgument
import com.example.inventoryapp.ui.home.HomeDestination
import com.example.inventoryapp.ui.home.HomeScreen
import com.example.inventoryapp.ui.item.ItemDetailsDestination
import com.example.inventoryapp.ui.item.ItemDetailsScreen
import com.example.inventoryapp.ui.item.ItemEditDestination
import com.example.inventoryapp.ui.item.ItemEditScreen
import com.example.inventoryapp.ui.item.ItemEntryDestination
import com.example.inventoryapp.ui.item.ItemEntryScreen


/**
 * 导航主机组件 - InventoryNavHost
 * 功能：定义整个应用的导航图
 * 参数：
 * navController: NavHostController- 导航控制器，管理导航状态
 * modifier: Modifier = Modifier- 可选的修饰符，用于自定义布局
 */
@Composable
fun InventoryNavHost(
    navController: NavHostController,
    modifier: Modifier = Modifier
) {
    /**
     * 导航主机实现 - NavHost
     * navController：传入的导航控制器
     * startDestination：起始路由（这里是首页）
     * modifier：传递的修饰符
     */

    NavHost(
        navController = navController,
        startDestination = HomeDestination.route,
        modifier = modifier
    ) {
        /**
         *  导航图定义（Lambda 内部）
         *  首页路由
         *  路由：HomeDestination.route（通常是 "home"）
         * 功能：
         * 显示 HomeScreen组件
         * 提供两个导航回调：
         * navigateToItemEntry：导航到添加新物品页面
         * navigateToItemUpdate：导航到物品详情页面，传递物品ID参数
         */
        composable(route = HomeDestination.route) {
            HomeScreen(
                navigateToItemEntry = { navController.navigate(ItemEntryDestination.route) },
                navigateToItemUpdate = {
                    navController.navigate("${ItemDetailsDestination.route}/${it}")
                }
            )
        }

        /**
         * 添加新物品路由
         * 路由：ItemEntryDestination.route（通常是 "item_entry"）
         * 功能：
         * 显示 ItemEntryScreen组件
         * 提供两个返回导航选项：
         * navigateBack：弹出当前页面（返回上一页）
         * onNavigateUp：导航回上一级（兼容不同导航场景）
         */
        composable(route = ItemEntryDestination.route) {
            ItemEntryScreen(
                navigateBack = { navController.popBackStack() },
                onNavigateUp = { navController.navigateUp() }
            )
        }

        /**
         * 物品详情路由（带参数）
         * 路由：ItemDetailsDestination.routeWithArgs（通常是 "item_details/{itemId}"）
         * 参数：
         * arguments：定义路由参数列表
         * navArgument：声明名为 itemIdArg的参数
         * type = NavType.IntType：指定参数类型为整数
         * 功能：
         * 显示 ItemDetailsScreen组件
         * 提供两个导航回调：
         * navigateToEditItem：导航到编辑物品页面，传递当前物品ID
         * navigateBack：导航回上一级
         */
        composable(
            route = ItemDetailsDestination.routeWithArgs,
            arguments = listOf(navArgument(ItemDetailsDestination.itemIdArg) {
                type = NavType.IntType
            })
        ) {
            ItemDetailsScreen(
                navigateToEditItem = { navController.navigate("${ItemEditDestination.route}/$it") },
                navigateBack = { navController.navigateUp() }
            )
        }

        /**
         * 编辑物品路由（带参数）
         * 路由：ItemEditDestination.routeWithArgs（通常是 "item_edit/{itemId}"）
         * 参数：
         * 类似详情页，定义整数类型的 itemIdArg参数
         * 功能：
         * 显示 ItemEditScreen组件
         * 提供两种返回方式：
         * navigateBack：弹出当前页面
         * onNavigateUp：导航回上一级
         */
        composable(
            route = ItemEditDestination.routeWithArgs,
            arguments = listOf(navArgument(ItemEditDestination.itemIdArg) {
                type = NavType.IntType
            })
        ) {
            ItemEditScreen(
                navigateBack = { navController.popBackStack() },
                onNavigateUp = { navController.navigateUp()}
            )
        }
    }
}

/**
 * 关键设计特点
 * 参数化路由：
 * 使用 routeWithAgs定义带参数的路径（如 item_details/{itemId}）
 * 通过 navArgument声明参数类型（整数）
 * 导航控制器传递：
 * 所有导航操作都通过 navController执行
 * 避免直接操作导航状态，保持组件解耦
 * 多种返回策略：
 * popBackStack()：从堆栈中弹出当前页面
 * navigateUp()：导航回上一级（更通用的返回方式）
 * 类型安全参数：
 * 使用 NavType.IntType确保参数类型正确
 * 避免运行时类型错误
 * 组件解耦：
 * 屏幕组件不需要知道导航细节
 * 通过回调函数执行导航操作
 * 导航流程示例
 * 从首页到添加物品：
 * // 在 HomeScreen 中
 * Button(onClick = navigateToItemEntry) { /*...*/ }
 *
 * // 在 NavHost 中处理
 * navController.navigate(ItemEntryDestination.route)
 * 从首页到物品详情：
 * // 在 HomeScreen 中点击某个物品
 * ItemCard(onClick = { navigateToItemUpdate(item.id) })
 *
 * // 在 NavHost 中处理
 * navController.navigate("${ItemDetailsDestination.route}/${item.id}")
 * 从详情到编辑：
 * // 在 ItemDetailsScreen 中点击编辑按钮
 * Button(onClick = { navigateToEditItem(itemId) })
 *
 * // 在 NavHost 中处理
 * navController.navigate("${ItemEditDestination.route}/$itemId")
 * 返回操作：
 * // 在编辑页面点击取消
 * Button(onClick = navigateBack) { /*...*/ }
 *
 * // 执行
 * navController.popBackStack()
 * 扩展建议
 * 嵌套导航：
 * navigation(startDestination = "main", route = "home") {
 *     composable("main") { /*...*/ }
 *     composable("detail") { /*...*/ }
 * }
 * 深度链接支持：
 * composable(
 *     route = "item/{id}",
 *     deepLinks = listOf(navDeepLink { uriPattern = "app://item/{id}" })
 * ) { /*...*/ }
 * 动画过渡：
 * composable(
 *     route = "detail",
 *     enterTransition = { /* 进入动画 */ },
 *     exitTransition = { /* 退出动画 */ }
 * ) { /*...*/ }
 *
 */